home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 July / EnigmA AMIGA RUN 20 (1997)(G.R. Edizioni)(IT)[!][issue 1997-07 & 08][EAR-CD IV].iso / earcd / biz / patch / irj.lha / IRJ.doc < prev    next >
Text File  |  1997-02-26  |  16KB  |  417 lines
  1.  
  2.   IRJ.doc                                                            26-Feb-97
  3.  
  4.  
  5.  
  6.   Intro:
  7.  
  8.       Welcome, my fellow Imagine users!  This is the third(final) release of the
  9.  
  10.   Imagine-Requester-Jester (also known as IRJ) for the Amiga release of
  11.  
  12.   Imagine5.0 by Impulse.  For versions of IRJ that work with previous versions
  13.  
  14.   of Imagine, check out Aminet.
  15.  
  16.       Let me preface this doc file by saying that I hate writing docs - I'm
  17.  
  18.   a programmer, not a tech writer.  3^)
  19.  
  20.       What does IRJ do?  Well, IRJ replaces Imagine's calls to its own file
  21.  
  22.   requesters with calls to the system ASL file requester.  IRJ maintains
  23.  
  24.   seperate paths for different file operations(better explained later).  IRJ
  25.  
  26.   can be used to either attach itself to a running version of Imagine, or can
  27.  
  28.   itself launch Imagine.  IRJ runs from the CLI or from its Workbench icon.
  29.  
  30.  
  31.  
  32.   System requirements:
  33.  
  34.       First I should say that IRJ requires WB2.04+, which I hope you are all
  35.  
  36.   running.  This version of IRJ only works with Imagine5.0.  This is because
  37.  
  38.   IRJ overwrites the file requester subroutine calls made by Imagine at known
  39.  
  40.   specific in the program.  IRJ does not modify your original version of
  41.  
  42.   Imagine - rather it 'hotpatches' Imagine once it's in memory.
  43.  
  44.  
  45.  
  46.   Installation:
  47.  
  48.       type 'lha x IRJ.lha ram:' at a CLI prompt ... some of the icons & dirs
  49.  
  50.   included in this archive require being placed in ram:  If you de-arc'd this
  51.  
  52.   package to another location, some of the icons may need to be modified.
  53.  
  54.   After you gain confidence with IRJ you may move the executable to somewhere
  55.  
  56.   in your command path (say c:), and copy the supplied icons and IRJ config
  57.  
  58.   files to whereever you want.  If you keep the icons, be sure to edit the
  59.  
  60.   tooltypes to reflect any changes you make.
  61.  
  62.  
  63.  
  64.   Usage:
  65.  
  66.       IRJ is designed to be used from the CLI or via a WorkBench icon.
  67.  
  68.  
  69.       From WorkBench:  double-click any of the included icons.
  70.  
  71.          IRJ recognizes the following icon tooltypes:
  72.          -------------------------------------------------------
  73.          CONFIG=            <path&filename of a IRJ config file>
  74.          IMAGINENAME=       <name of imagine executable>
  75.          IMAGINEDIR=        <path to imagine executable>
  76.          IMAGINESTACK=      <stack size to start imagine with>
  77.          IMAGINEPRIORITY=   <adjust imagine priority>
  78.          PUBSCREEN=         <open Imagine's screen as a public screen>
  79.          QUIT=              <quit IRJ without quitting imagine>
  80.  
  81.            these relate closely to the CLI usage except the keywords may not
  82.          be abbreviated and QUIT is not a switch but rather a booleen (ie
  83.          QUIT=T, or QUIT=t), same goes for the new option PUBSCREEN
  84.  
  85.  
  86.       ...or...
  87.  
  88.  
  89.       From any CLI prompt, type 'IRJ help' to find the command template:
  90.  
  91.          IRJ CONFIG/K,ID=IMAGINEDIR/K,IN=IMAGINENAME/K,IS=IMAGINESTACK/N,
  92.             IP=IMAGINEPRIORITY/N,PUBSCREEN/S,QUIT/S
  93.  
  94.          here are a few CLI examples:
  95.  
  96.             IRJ CONFIG=ram:IRJ.config
  97.             IRJ IP=-1
  98.             IRJ
  99.             IRJ QUIT
  100.             IRJ IMAGINENAME=imagine4.0_fp ID=imagine: IS=20000 PUBSCREEN
  101.  
  102.  
  103.  
  104.   How it works:
  105.  
  106.       When first run, IRJ reads its default config file (unless another is
  107.  
  108.   specified).  IRJ then looks around to see if Imagine is already running; if
  109.  
  110.   it is, IRJ attaches itself to Imagine, changes Imagine's priority (if
  111.  
  112.   specified) and then waits for the user to quit Imagine, or for a subsequent
  113.  
  114.   invocation of IRJ to signal this one to detach from Imagine and quit.
  115.  
  116.       Whew! ok, so if the first IRJ doesn't find Imagine already running,
  117.  
  118.   it (IRJ) checks IMAGINEDIR and IMAGINENAME to see if you want IRJ to launch
  119.  
  120.   Imagine -
  121.  
  122.    -if not, IRJ waits in the background taking up no time waiting for the user
  123.  
  124.   to start Imagine in some other fashion; when it shows up, IRJ will attach
  125.  
  126.   itself and wait for the user to quit Imagine, or for a subsequent invocation
  127.  
  128.   of IRJ to signal this one to detach from Imagine and quit.
  129.  
  130.    -if so, IRJ will change its current dir to IMAGINEDIR (which must contain
  131.  
  132.   Imagine.pic & Imagine.config - well, not really, but that's where Imagine
  133.  
  134.   is going to look for those files) and then run the program IMAGINENAME.
  135.  
  136.   The values of IMAGINESTACK & IMAGINEPRIORITY are both applied if specified.
  137.  
  138.       On subsequent invocations either from an icon or from another CLI (that
  139.  
  140.   first CLI won't return until IRJ finishes) IRJ first checks if the user has
  141.  
  142.   specified the QUIT option.  If so, this IRJ signals the first IRJ to detach
  143.  
  144.   from Imagine (that is if it had already done so - there's no guarantee) and
  145.  
  146.   then quit.  If no QUIT option, IRJ will then read a IRJ config file if
  147.  
  148.   specified by CONFIG= and pass it on to the original IRJ.
  149.  
  150.    Then, if Imagine is running, IRJ will change Imagine's priority (if
  151.  
  152.   specified) and then quit, ignoring any other arguments.
  153.  
  154.    Else, since Imagine is not running, check IMAGINEDIR and IMAGINENAME to see
  155.  
  156.   if user wants IRJ to launch Imagine.  If not, quit cause I don't see what
  157.  
  158.   you're trying to accomplish.  If so, launch Imagine as I've described before.
  159.  
  160.       I'm sorry that was all so complicated but that's just the way the program
  161.  
  162.   logic worked out.
  163.  
  164.       As far as the PUBSCREEN option goes, IRJ will only make Imagine's screen
  165.  
  166.   public if Imagine has not already opened it's screen.  This option was added
  167.  
  168.   late in the development of IRJ and has not been tested as well as the rest
  169.  
  170.   of the program.  Imagine's public screen is SCREEN_1, I tried making this
  171.  
  172.   user definable, but it was too much work.  Also, Imagine's screen was not
  173.  
  174.   designed to be a public screen, so it's up to you to close all visiting
  175.  
  176.   windows or you may expect a crash.  And, since Imagine's screen was not
  177.  
  178.   designed to be a public screen, your windows get be overwritten (trashed)
  179.  
  180.   in some circumstances.
  181.  
  182.  
  183.  
  184.   Configuring IRJ to your system:
  185.  
  186.       IRJ increases Imagine's flexibility by keeping track of several seperate
  187.  
  188.   paths.  These include directories for objects, DXFs, forms, cycles, effects,
  189.  
  190.   splinepaths, brushmaps, attributes, textures, and particals.
  191.  
  192.       When a new project is begun, Imagine used to create only a directory for
  193.  
  194.   objects in the main <project>.imp drawer.  Now, IRJ creates additional dirs
  195.  
  196.   for those I just listed.  It's up to you what they are called and where they
  197.  
  198.   are created.  They can even point to the same thing (maybe you want your
  199.  
  200.   cycle dir to be the same as your object dir or maybe even put your cycle dir
  201.  
  202.   in your object dir).  By using wildcards in your CONFIG file, you can even
  203.  
  204.   include the project name in part of the directory (the usefullness of this
  205.  
  206.   is explained later).
  207.  
  208.       IRJ config files are plain text files you create with your own word
  209.  
  210.   processor.  Config labels must start in column one and must contain at least
  211.  
  212.   one space between the label and its definition.  Supplying a config label
  213.  
  214.   (followed by at least 1 space) with nothing else on the line tells IRJ to
  215.  
  216.   use the directory from which Imagine was run.  Comments are not allowed on
  217.  
  218.   the same line as a config label definition.
  219.  
  220.       I'll go through the config labels group by group.  To see all of them
  221.  
  222.   listed together see the file from the archive ram:IRJdefaults.cfg
  223.  
  224.  
  225.   configlabel    IRJ-default    description
  226.   -----------    -----------    ----------------------------------------------
  227.   PREFSfile                     Default Imagine config file in prefs editor.
  228.  
  229.   PROJECTdir                    This is the directory Imagine creates/opens
  230.                                 your projects in/from.  You can of course use
  231.                                 the file requester to change this.
  232.  
  233.   PROJECTfile                   Default project name. Imagine creates a
  234.                                 directory for you called <project>.imp in
  235.                                 which it adds a file called 'staging' - it's
  236.                                 this file you load when you want to open a
  237.                                 project(ie. PROJECTS/JESTER.imp/staging = the
  238.                                 JESTER project). Just to be clear here, for
  239.                                 the example just given, PROJECTdir would be
  240.                                 PROJECTS and PROJECTfile would be JESTER, ok?
  241.  
  242.   SUBPROJECTfile                Default subproject name. The same as before,
  243.                                 when Imagine creates a new Subproject, it
  244.                                 creates a dir called <subproject>.pix in
  245.                                 which a file called 'specs' exists, it's
  246.                                 this file you Open to tell Imagine which
  247.                                 subproject you really mean.
  248.  
  249.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  250.  
  251.   When creating a new subproject, these config labels replace Imagine's idea
  252.   of defaults in the subproject requester-
  253.  
  254.   PIXdir                        Default path to render pix to. Useful for
  255.                                 rendering to RAM: or even a PAR
  256.  
  257.   ANIMdir                       Default path to save anims to.
  258.  
  259.   RENDER40       000            Combine these bits to set button state in
  260.                                 subproject requester. Imagine4.0+
  261.                                  100 - flip fields
  262.                                  010 - field rendered
  263.                                  001 - stereo 3D
  264.  
  265.   RENDERmethod   4              Set this to set render method in subproject
  266.                                 requester. Options are:
  267.                                  0 - b/w wire
  268.                                  1 - b/w shade
  269.                                  2 - color wire
  270.                                  3 - color shade
  271.                                  4 - scanline
  272.                                  5 - trace
  273.  
  274.   WIDTH          320            Sets render size and render aspect values
  275.   HEIGHT         200            in subproject requester.
  276.   XASPECT        6
  277.   YASPECT        7
  278.  
  279.   FILEformat     0              Sets file format for rendering. Options are:
  280.                                  0 - rgbn-12bit
  281.                                  1 - ilbm-12bit
  282.                                  2 - rgbn-24bit
  283.                                  3 - ilbm-24bit
  284.                                  4 - seperate r,g,b
  285.                                  5 - dctv
  286.  
  287.   VIEWmode       0100 (HAM)     Sets state of view mode buttons in sub-
  288.                                 project requester.  You can combine some of
  289.                                 these options:
  290.                                  1000 - AAcs
  291.                                  0100 - HAM
  292.                                  0010 - hires
  293.                                  0001 - lace
  294.  
  295.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  296.                                 
  297.   These config labels determine where the various paths IRJ keeps track of
  298.   start out at-
  299.  
  300.   OBJECTdir      @/objects      Each of these directories are kept track of    
  301.   DXFdir         @/objects      independantly.  Always double check the path
  302.   FORMdir        @/objects      you are saving objects/attribs/splines/etc to
  303.   CYCLEdir       @/objects      since you probably aren't used to having so
  304.   SPLINEdir      @/objects      many paths to manage.  It isn't hard to lose
  305.   BRUSHMAPSdir                  track of which path you are manipulating.
  306.   ATTRIBSdir     @/objects      
  307.   TEXTURESdir                     
  308.   EFFECTSdir                      
  309.   PARTICALSdir   @/objects
  310.   REXXdir        rexx:imagine   ...Imagine5.0 only
  311.  
  312.   The character '@' has special meaning to IRJ for these ten config labels.
  313.   It is replaced with the current PROJECT name.  You'll get unpredictable
  314.   results if you don't open a PROJECT before using a directory with an '@' 
  315.   in it. Some examples (assuming project opened is named 'JESTER')-
  316.  
  317.     @/objects     = JESTER.imp/objects
  318.     @/forms       = JESTER.imp/forms
  319.     @/objects/dxf = JESTER.imp/objects/dxf
  320.     brushmaps/@   = brushmaps/JESTER     <- you can put it at the end too.
  321.     dh1:attribs/@ = dh1:attribs/JESTER   <- '.imp' is chopped off the end
  322.  
  323.   When you create a new PROJECT, IRJ will create directories for each of
  324.   the ten directories it manages.  If you don't want to create all these
  325.   directories just define them to point at ram:
  326.  
  327.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  328.  
  329.   IRJ allows pattern matching for each of the filerequesters it manages.  I
  330.   don't use this myself but some people like using file extensions.  Here are
  331.   the config labels, IRJ defaults and some suggestions-
  332.  
  333.   PROJECTpat        ~(#?.info)      
  334.   NEWSUBPROJECTpat  #?.pix
  335.   OPENSUBPROJECTpat #?specs
  336.   PREFSpat          #?.config
  337.   OBJECTpat         ~(#?.info)        or...  #?.iob
  338.   DXFpat            ~(#?.info)               #?.dxf
  339.   FORMpat           ~(#?.info)
  340.   CYCLEpat          ~(#?.info)
  341.   SPLINEpat         ~(#?.info)
  342.   BRUSHMAPSpat      ~(#?.info)               #?.iff
  343.   ATTRIBSpat        ~(#?.info)               #?.atr
  344.   TEXTURESpat       #?.itx
  345.   EFFECTSpat        #?.ifx
  346.   PARTICALSpat      ~(#?.info)
  347.   REXXpat           #?.irx
  348.  
  349.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  350.  
  351.   With these config labels, you can position and resize the filerequesters-
  352.  
  353.   REQwidth          328
  354.   REQheight         222
  355.   REQleftedge       156
  356.   REQtopedge        86
  357.  
  358.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  359.  
  360.  
  361.  
  362.  
  363.   Inevitable plea for money:
  364.  
  365.       I put a lot of time into creating IRJ and making it so configurable for
  366.  
  367.   all to use.  If you use this program and feel it's worth five bucks($5),
  368.  
  369.   please stuff it in an envelope and send it to me.  You can also drop me a
  370.  
  371.   postcard with your comments about IRJ or just say hi!; I'd like to know how
  372.  
  373.   many AMIGA users are left out there. (fewer than the last time I sent this out)
  374.  
  375.       Please post this archive to your local BBS's and let your friends know
  376.  
  377.   about IRJ!
  378.  
  379.  
  380.     Kirk Piepho                    email:  rexx@wavefront.com
  381.     2383 N. Dale St. #307
  382.     Roseville, MN 55113            <- jeesh, just 20 minutes from Impulse
  383.     U.S.A.                         world headquarters but in no way related
  384.                                    or connected with the aforementioned
  385.                                    company. Small world eh?
  386.  
  387.   *****************************************************************************
  388.   *****************************************************************************
  389.  
  390.   Well, after releasing the first IRJ for Imagine, I had some dialog with
  391.  
  392.   Impulse, the result of which was my being contracted to add Arexx support
  393.  
  394.   to Imagine5.0  I'm not sure if I got the job because of IRJ, or because of
  395.  
  396.   my proximity to Impulse world headquarters !8^)  hmmm....  Anyhow, if you
  397.  
  398.   don't have Imagine5.0 or didn't know of it's existance, call up Impulse at
  399.  
  400.   1-612-425-0557.  I'm not being paid for this advertisement, just trying to
  401.  
  402.   keep the program alive.
  403.  
  404.   *****************************************************************************
  405.   *****************************************************************************
  406.  
  407.   ps. _If_ you do want to send me money for IRJ, I'll take checks or cash (I've
  408.   never had any trouble sending cash thru the mail, so don't let that stop you).
  409.   And of course I know you'll have no trouble getting an envelope and a stamp
  410.   and taking all that time to address it and to write a check and ...that's
  411.   _IF_ you feel it's worth it (IRJ that is - heck, this doc file is worth five
  412.   bucks - I hate writing all this but hope I did all right).
  413.  
  414.  
  415.   See yah!
  416.  
  417.